home *** CD-ROM | disk | FTP | other *** search
/ BCI NET / BCI NET Dec 94.iso / archives / programming / blitzbasic / blitz-list200994.lha / blitz-list / EnJoy12.lha / EnhancedJoystickLib12 / EnhancedJoystickLib.doc next >
Encoding:
Text File  |  1994-07-14  |  21.3 KB  |  615 lines

  1. *****************************************************************************
  2.  
  3.      Please do no distribute this version of EnhancedJoystickLib!!!
  4.  
  5.      This  version  is  only a Beta release and has been released into
  6.      the InterNet blitz-list mailing list.
  7.  
  8.      If  I get no major bugs within a few days of this release, I will
  9.      release  a  full version (with an allocated lib number) which can
  10.      be distributed.
  11.  
  12. Note
  13. ====
  14.      Make  sure  that  you  save  anything  you  write which uses this
  15.      library  as  ASCII  as  well as tokenised. This is to ensure easy
  16.      transition   when   the  full  release  version  is  distributed.
  17.  
  18.  
  19. *****************************************************************************
  20.  
  21. Command List
  22. ============
  23.     n.l=IsLowLevel
  24.      SetJoyPortType port,type
  25.      n.b=GetJoyPortType(port)
  26.     n.b=NewJoyB(port)
  27.     n.b=OldJoyB
  28.      n.b=NewJoyX(port)
  29.     n.b=OldJoyX
  30.     n.b=NewJoyY(port)
  31.     n.b=OldJoyY
  32.      n.b=NewJoyR(port)
  33.     n.b=OldJoyR
  34.      n.l=NewJoyData(port)
  35.     n.l=OldJoyData
  36.      n.b=JoyRToJoyX(rotation)
  37.     n.b=JoyRToJoyY(rotation)
  38.      n.b=JoyXYToJoyR(x,y)
  39.  
  40.  
  41. *****************************************************************************
  42.  
  43.    Library Name: EnhancedJoystickLib
  44. Library Version: 1.2 Beta
  45.  
  46.  Library Number: 11 (temporary, will change in the future!!!)
  47.      Written by: Chi Wai Lee
  48.       Copyright: 1994 Spiral Vortex Productions.
  49.           Dated: 16/7/94
  50.  
  51.  E-Mail Contact: Chi Wai Lee@2:2500/167.9         (FidoNet)
  52.                             @39:138/16.9          (AmigaNet)
  53.                  C.W.Lee-CSSE93@cs.bham.ac.uk     (InterNet)
  54.                  CCA93039@ibm3090.bham.ac.uk      (InterNet)
  55.  
  56.  Snail-Mail    : Chi Wai Lee
  57.                  9 Fraser Road
  58.                  Greet, Birmingham
  59.                  United Kingdom
  60.                  B11 2NA
  61.  
  62. *****************************************************************************
  63.  
  64. READ THIS
  65. =========
  66.  
  67.      THERE IS NO WARRANTY FOR THE PROGRAMS, TO THE EXTENT PERMITTED BY
  68.      APPLICABLE  LAW.  EXCEPT  WHEN  OTHERWISE  STATED  IN WRITING THE
  69.      COPYRIGHT  HOLDERS  AND/OR OTHER PARTIES PROVIDE THE PROGRAMS "AS
  70.      IS"  WITHOUT  WARRANTY  OF ANY KIND, EITHER EXPRESSED OR IMPLIED,
  71.      INCLUDING,   BUT  NOT  LIMITED  TO,  THE  IMPLIED  WARRANTIES  OF
  72.      MERCHANTABILITY  AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE
  73.      RISK  AS  TO  THE QUALITY AND PERFORMANCE OF THE PROGRAMS IS WITH
  74.      YOU.  SHOULD THE PROGRAMS PROVE DEFECTIVE, YOU ASSUME THE COST OF
  75.      ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
  76.  
  77.      IN  NO  EVENT  UNLESS  REQUIRED BY APPLICABLE LAW OR AGREED TO IN
  78.      WRITING  WILL  ANY  COPYRIGHT  HOLDER, OR ANY OTHER PARTY WHO MAY
  79.      REDISTRIBUTE  THE  PROGRAMS  AS PERMITTED ABOVE, BE LIABLE TO YOU
  80.      FOR  DAMAGES,  INCLUDING  ANY  GENERAL,  SPECIAL,  INCIDENTAL  OR
  81.      CONSEQUENTIAL  DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE
  82.      THE  PROGRAMS  (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA
  83.      BEING  RENDERED  INACCURATE  OR  LOSSES SUSTAINED BY YOU OR THIRD
  84.      PARTIES  OR  A  FAILURE OF THE PROGRAMS TO OPERATE WITH ANY OTHER
  85.      PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF
  86.      THE POSSIBILITY OF SUCH DAMAGES.
  87.  
  88.  
  89. *****************************************************************************
  90.  
  91. AND THIS
  92. ========
  93.  
  94.      No  warranty,  either express or implied, is made with respect to
  95.      the fitness or merchantability of EnhancedJoystickLib.
  96.  
  97.      Chi  Wai  Lee (referred to as "the author"), reserve the right to
  98.      not develop any future versions of EnhancedJoystickLib.
  99.  
  100.      The  author  will  try to make a good faith attempt at correcting
  101.      any  problems  if  any are discovered, but is in no way required,
  102.      nor bound to correct them.
  103.  
  104.      The  author  neither assume nor accept any responsibility for the
  105.      use  or  misuse  of  these  programs.  They also will not be held
  106.      liable  for  damages  or  any  compensation  beyond  the original
  107.      registration  fee  due  to  loss  of  profit or any other damages
  108.      arising out of the use, or inability to use this program.
  109.  
  110.      The  author  will  not  be liable for any damage arising from the
  111.      failure  of  these  programs  to  perform  as  described,  or any
  112.      destruction  of  other  programs  or  data  residing  on a system
  113.      attempting  to  run  the  programs.  While we know of no damaging
  114.      errors,  the  user  of  these  programs uses it at his or her own
  115.      risk.
  116.  
  117.  
  118. *****************************************************************************
  119.  
  120. Conditions Of Use
  121. =================
  122.  
  123.      1)..You  may copy and distribute verbatim copies of the programs'
  124.      executable  code  and  documentation  as  you  receive it, in any
  125.      medium,  provided  that you publish only the original, unmodified
  126.      program,  with  all copyright notices and disclaimers or warranty
  127.      intact  and including all the accompanying documentation, example
  128.      files and anything else that came with the original.
  129.  
  130.      2)..You may use this program for an evaluation period of 30 days.
  131.      Thereafter, you *HAVE* to register or acknowledge the use of this
  132.      program with the author (see condition 3). If you do not register
  133.      after  the elapse of the evaluation period (see condition 3), you
  134.      are in violation of the Conditions Of Use (see condition 6.)
  135.  
  136.      3)..The  normal evaluation period of this program is 30 days. You
  137.      may  extend  this period to 60 days if you acknowledge the use of
  138.      this program by sending the author a postcard. Doing so will only
  139.      extend  the  evaluation  period  and  does  not  change any other
  140.      Conditions Of Use.
  141.  
  142.      4)..For  this library to be incorporated into any distributed (in
  143.      any  medium) software of type ShareWare, Public Domain, FreeWare,
  144.      etc.,  (i.e.  Not  commercial  -  Fee for use must be below 20 UK
  145.      pounds or equivalant cost) this library *MUST* be registered with
  146.      the author.
  147.  
  148.      5)..The  use of this library for commercial software (Fee for use
  149.      above  20  UK  pounds  or  equivalant)  is prohibited. You *MUST*
  150.      contact the author for a commercial license agreement.
  151.  
  152.      6)..If you are in violation of any of the above Conditions of Use
  153.      you  *MUST* remove all trace of this program and any accompanying
  154.      material.
  155.  
  156.      7)..If  any  software  using  this  library  is  distributed (see
  157.      condition 4) without the author of the software being registered.
  158.      I  have  the  right  to  remove  the  offending software from any
  159.      storage medium.
  160.  
  161.  
  162. *****************************************************************************
  163.  
  164. Registering
  165. ===========
  166.  
  167.      The registration fee for this program is *ONLY* 5 UK pounds for a
  168.      period  of  one  year, thereafter for you to continue use of this
  169.      program,  you must re-register or you will be in violation of the
  170.      Conditions Of Use, or 10 UK pounds for an indefinite period.
  171.  
  172.      No other form of currency will be accepted!!!
  173.  
  174.      Registering  allows the use of any version of this library in any
  175.      of  your  programs during the period in which you are registered.
  176.      Registering does  not  give  you  any  extra,  new, faster, etc.,
  177.      functions although you may gain more help from me.
  178.  
  179.      This software is distributed in the *TRUE* sense of ShareWare.
  180.  
  181.  
  182. *****************************************************************************
  183.  
  184. Requirements
  185. ============
  186.  
  187.      Most  of these functions *REQUIRE* C='s lowlevel.library as found
  188.      in WorkBench 3.1 and some versions of WorkBench 3.0.
  189.  
  190.  
  191. *****************************************************************************
  192.  
  193. Installation
  194. ============
  195.  
  196. 1)..Temporary installation.
  197.      Copy the .obj file into your BlitzLibs:Userlibs/ directory and do
  198.      a  RELOAD  LIBS  from  the  compiler  menu  within Blitz. The new
  199.      commands will be usuable until you quit.
  200.  
  201. 2)..Normal installation.
  202.      Copy  the  .obj  file into you BlitzLibs:Userlibs/ directory. Now
  203.      run  the  tool MAKEDEFLIBS. This should create a new DEFLIBS file
  204.      which  contains  the new commands. These new commands will now be
  205.      usable  whenever  you  load  Blitz. Note that the commands aren't
  206.      available for any currently running Blitz. You should do a RELOAD
  207.      LIBS from the compiler menu to enable the new commands.
  208.  
  209.      If  you cannot find the MAKEDEFLIBS tool, it may be archived in a
  210.      file called libtools.lha within the includes/ directory.
  211.  
  212.      If  you  still  can't  get it to work, contact me and I'll try to
  213.      sort it out.
  214.  
  215.  
  216. *****************************************************************************
  217.  
  218. Brief Comment
  219. =============
  220.  
  221.      The  reason  I have written these function is that I needed a way
  222.      of  reading  the joystick port's second fire button. Obviously, I
  223.      came  across  Richard  Elmore's JoyC() function but from my tests
  224.      showed that it was not 100% reliable when reading the second fire
  225.      button on joystick port 1.
  226.  
  227.      My  tests showed that it works fine in test situations (i.e. loop
  228.      testing), but failed (always reported button two is pressed) when
  229.      put  in a real life situation (my current project.) I have traced
  230.      the   problem   to   the   way   the   joystick   port   uses   a
  231.      capacitor-potentiometer  for  the  second  fire button unlike the
  232.      normal fire button which uses a switch.
  233.  
  234.      [Richard - contact me if you want a bit more info on the prob.]
  235.  
  236.      I  therefore  set  about  on  writing my own routines to read the
  237.      joystick    port.    By   coincidence,   I   came   across   C='s
  238.      lowlevel.library  which  has  a  very comprehensive joystick port
  239.      command   set.   Since   this   library   is  based  around  C='s
  240.      lowlevel.library,  this  library is therefore upwardly compatible
  241.      with future Amiga OS' (If the Amiga survives)
  242.  
  243.      The  way  this  library  has  been  designed  allows for a single
  244.      command  to read the complete state of the selected joystick port
  245.      and  then  allow  following  commands to use the stored state for
  246.      it's data.
  247.  
  248.      For example:
  249.  
  250.           x.b=JoyX(1)
  251.           y.b=JoyY(1)
  252.           r.b=JoyR(1)
  253.           b.b=JoyB(1)
  254.  
  255.      can  produce  inconsistent  results, the JoyR function may return
  256.      different values than the above JoyX and JoyY functions.
  257.  
  258.      On the other hand, using the functions in this library...
  259.  
  260.           x.b=NewJoyX(1)
  261.           y.b=OldJoyY
  262.           r.b=OldJoyR
  263.           b.b=OldJoyB
  264.  
  265.      will  ensure  consistent  results due to all the results are from
  266.      *ONE* specific reading of the joystick port.)
  267.  
  268.      In  addition  to  these  new  joystick reading command, there are
  269.      several  conversion  functions (e.g. convert a JoyR result into a
  270.      JoyX result.)
  271.  
  272.      There  is  however  one  disadvantage,  namely  speed. The actual
  273.      joystick   port  reading  is  done  using  a  function  from  the
  274.      lowlevel.library  and  to  be  honest  isn't  very fast, but only
  275.      slightly slower than the normal Blitz joystick function.
  276.  
  277.      But  then  again  there are some speed advantages as well. Due to
  278.      the way this library has been designed, you only need to read the
  279.      joystick  port  once  but  still able to get several results from
  280.      this read.
  281.  
  282.      For example:
  283.  
  284.           b.b=NewJoyB(1)
  285.           x.b=JoyX(1)
  286.           y.b=JoyY(1)
  287.           r.b=JoyR(1)
  288.  
  289.      would be *MUCH* slower than
  290.  
  291.           b.b=NewJoyB(1)
  292.           x.b=OldJoyX
  293.           y.b=OldJoyY
  294.           r.b=OldJoyR
  295.  
  296.      as  the  OldJoy...  functions  are  using  a  stored state of the
  297.      joystick port instead of reading in a new value.
  298.  
  299.  
  300. *****************************************************************************
  301.  
  302. Version 0.9 (13/7/94) First Public Beta Release
  303.  
  304. Version 1.0 (13/7/94)
  305.      Decided to halt release for a few hours...
  306.      Changed  some  of  the  names  of  the functions. Will not affect
  307.      anyone cos no one has this library yet <G>
  308.  
  309. Version 1.1 (14/7/94) First Public Beta Release, Again
  310.      Add SetJoyPortType() and GetJoyPortType() functions.
  311.  
  312. Version 1.2 (16/7/94) Second Public Beta Release
  313.     SetJoyPortType() does not update the OldJoy... data anymore.
  314.     GetJoyPortType() now accepts a port number.
  315.  
  316.  
  317. *****************************************************************************
  318.  
  319.      All  references  to  joystick  port  assumes 0 being the standard
  320.      mouse   port,   1   being   the   standard   joystick  port.  The
  321.      lowlevel.library's  ReadJoyPort()  function  suggests that it can
  322.      also accept port 2 and 3 (four player adaptor???)
  323.  
  324.      I  have  not  really tested for these, but know that if you enter
  325.      any values other than 0-3 will always result in NULL returns.
  326.  
  327.      In this Beta release, I have included C='s lowlevel.library. This
  328.      is  strictly  speaking,  illegal  but  I  have  no  KS1.3, KS2.04
  329.      machines  to  test  this library on so am putting my trust in you
  330.      guys   for   beta   testing   this   library   on  other  machine
  331.      configurations.
  332.  
  333.  
  334. =============================================================================
  335.  
  336. Function:    IsLowLevel
  337. =========
  338.      Syntax: n.l=IsLowLevel
  339. Description:
  340.  
  341.      This   function   will   return   the   address   of   where  the
  342.      lowlevel.library  is  loaded.  If  the lowlevel.library cannot be
  343.      loaded, a value of 0 is returned.
  344.  
  345. WARNING
  346. =======
  347.      Make  sure  you  test  for  this  before  using  any of the below
  348.      functions which require the lowlevel.library.
  349.  
  350.  
  351. -----------------------------------------------------------------------------
  352.  
  353. Statement: SetJoyPortType
  354. =========
  355.      Syntax: SetJoyPortType port,type
  356. Description:
  357.  
  358.      This statement sets the specified port to a type of input device.
  359.  
  360.      Type      Device
  361.      0         AutoSense
  362.      1         Game Controller (CD^32 gamepad, etc.) (7 fire buttons)
  363.      2         Mouse
  364.      3         Joystick (upto two fire buttons)
  365.  
  366.      Please  note  that  this command *ONLY* affects the joystick port
  367.      functions  within  this  library. The default start-up setting is
  368.      AutoSense.  Also  note  that  the  way AutoSense works is that it
  369.      scans  the  port several times and decides depending on what type
  370.      of  data  is retrieved, what type of controller is attached. This
  371.      can  cause  a slight delay and sometimes spurious results for the
  372.      first  reading of the port.
  373.  
  374.      The  best  (suggested)  method  is  to set the port to a specific
  375.      controller  type  before using the port, therefore resulting in a
  376.      much faster read time and accurate readings.
  377.  
  378.      Setting the port to mouse has no real use due to the fact that no
  379.      mouse  support  commands  have  been included. The standard Blitz
  380.      mouse commands are sufficient for most needs.
  381.  
  382. NOTE
  383. ====
  384.      The  method  in  which  the  Game Controller (gamepad) has 7 fire
  385.      buttons  cause the read commands to be slower. This is not due to
  386.      shoddy programming but due to the way the fire buttons have to be
  387.      encoded  into  time  based  patterns  which  naturally requires a
  388.      certain time to decode back again.
  389.  
  390. WARNING
  391. =======
  392.      Setting  the port type to anything other than the above specified
  393.      ones can cause errors. Do so at your own risk!!!
  394.  
  395. HINT (1.2)
  396. ====
  397.      AutoSense will cause all read commands to that port to be slower.
  398.  
  399. QUESTION
  400. ========
  401.      I  noticed that the lowlevel.library's joystick port commands can
  402.      read  upto  4  devices. I have tried using a parallel four player
  403.      adaptor and have not been able to get *ANY* feedback from them. I
  404.      also noticed that ports 2 and 3 (joysticks 3 and 4) can *ONLY* be
  405.      set to Game Controller.
  406.  
  407.      This  leads me to a conclusion that a four player adaptor will be
  408.      release  specifically  for  the  CD32  (maybe usable on us normal
  409.      Amigas)  which  allows  for four gamepads (like the Sega and SNES
  410.      thingies.)
  411.  
  412.  
  413. -----------------------------------------------------------------------------
  414.  
  415. Function: GetJoyPortType
  416. =========
  417.      Syntax: n.b=GetJoyPortType(port)
  418. Description:
  419.  
  420.      This  function  returns  a  result  which represents what type of
  421.      controller  code  was used for the specified port. Note that this
  422.      function   only  represents  the  controller  code  and  not  the
  423.      controller type used.
  424.  
  425.      To find the controller type, you will need to do a SetJoyPortType
  426.      to  activate AutoSense and then wait for some input, before using
  427.      GetJoyPortType again.
  428.  
  429.      Result         Controller Type
  430.      0              Not Available
  431.      1              Game Controller (CD^32 gamepad, etc. 7 buttons)
  432.      2              Mouse
  433.      3              Joystick (upto two buttons)
  434.      4              Unknown
  435.  
  436.  
  437. -----------------------------------------------------------------------------
  438.  
  439. Function: NewJoyB
  440. =========
  441.      Syntax: n.b=NewJoyB(joystick port)
  442. Description:
  443.  
  444.      This  function  returns a byte which represents the current state
  445.      of  the  joystick  port  fire  buttons (all 7 of them, if you are
  446.      using  a  CD^32  gamepad or equivalant.)
  447.      The  state  of  the  port is also stored for use by the OldJoy...
  448.      functions.
  449.  
  450.           Dec  Bit  Button
  451.           1    0    Grey - Play/Pause; Middle Mouse
  452.           2    1    Charcoal - Reverse
  453.           4    2    Charcoal - Forward
  454.           8    3    Green - Shuffle
  455.           16   4    Yellow - Repeat
  456.           32   5    Red - Select; Left Mouse; Joystick Button One
  457.           64   6    Blue - Stop; Right Mouse; Joystick Button Two
  458.  
  459.  
  460. -----------------------------------------------------------------------------
  461.  
  462. Function: OldJoyB
  463. =========
  464.      Syntax: n.b=OldJoyB
  465. Description:
  466.  
  467.      This  function returns the joystick port fire buttons of the last
  468.      read joystick port state. See *NewJoyB* for return values.
  469.  
  470.  
  471. -----------------------------------------------------------------------------
  472.  
  473. Function: NewJoyX
  474. =========
  475.      Syntax: n.b=NewJoyX(joystick port)
  476. Description:
  477.  
  478.      This  function  returns  the current state of the joystick port X
  479.      direction.  If  the  joystick  is  held  left,  a  value of -1 is
  480.      returned.  If  the  joystick  is  held  right,  a  value of +1 is
  481.      returned.  Otherwise  a  value of 0 is returned.
  482.      The  state  of  the  port is also stored for use by the OldJoy...
  483.      functions.
  484.  
  485.  
  486. -----------------------------------------------------------------------------
  487.  
  488. Function: OldJoyX
  489. =========
  490.      Syntax: n.b=OldJoyX
  491. Description:
  492.  
  493.      This  function  returns the joystick port X direction of the last
  494.      read joystick port state. See *NewJoyX* for return values.
  495.  
  496.  
  497. -----------------------------------------------------------------------------
  498.  
  499. Function: NewJoyY
  500. =========
  501.      Syntax: n.b=NewJoyY(joystick port)
  502. Description:
  503.  
  504.      This  function  returns  the current state of the joystick port Y
  505.      direction. If the joystick is held up, a value of -1 is returned.
  506.      If  the  joystick  is  held  down,  a  value  of  +1 is returned.
  507.      Otherwise a value of 0 is returned.
  508.      The  state  of  the  port is also stored for use by the OldJoy...
  509.      functions.
  510.  
  511.  
  512. -----------------------------------------------------------------------------
  513.  
  514. Function: OldJoyY
  515. =========
  516.      Syntax: n.b=OldJoyY
  517. Description:
  518.  
  519.      This  function  returns the joystick port Y direction of the last
  520.      read joystick port state. See *NewJoyX* for return values.
  521.  
  522.  
  523. -----------------------------------------------------------------------------
  524.  
  525. Function: NewJoyR
  526. =========
  527.      Syntax: n.b=NewJoyR(joystick port)
  528. Description:
  529.  
  530.      This  function  returns  the current state of the joystick port R
  531.      direction.
  532.      The  state  of  the  port is also stored for use by the OldJoy...
  533.      functions.
  534.  
  535.           Direction           Return value
  536.           Up                  0
  537.           Up-Right            1
  538.           Right               2
  539.           Down-Right          3
  540.           Down                4
  541.           Down-Left           5
  542.           Left                6
  543.           Up-Left             7
  544.           No Direction        8
  545.  
  546.  
  547. -----------------------------------------------------------------------------
  548.  
  549. Function: OldJoyR
  550. =========
  551.      Syntax: n.b=OldJoyR
  552. Description:
  553.  
  554.      This  function  returns the joystick port R direction of the last
  555.      read joystick port state. See *NewJoyR* for return values.
  556.  
  557.  
  558. -----------------------------------------------------------------------------
  559.  
  560. Function: NewJoyData
  561. =========
  562.      Syntax: n.l=NewJoyData(joystick port)
  563. Description:
  564.  
  565.      This function calls the lowlevel.library's ReadJoyPort() function
  566.      and returns the resultant raw code.
  567.      The  state  of  the  port is also stored for use by the OldJoy...
  568.      functions.
  569.  
  570.  
  571. -----------------------------------------------------------------------------
  572.  
  573. Function: OldJoyData
  574. =========
  575.      Syntax: n.l=OldJoyData
  576. Description:
  577.  
  578.      This  function  returns  the result of the previous ReadJoyPort()
  579.      function call.
  580.  
  581.  
  582. -----------------------------------------------------------------------------
  583.  
  584. Function: JoyRToJoyX
  585. =========
  586.      Syntax: n.b=JoyRToJoyX(rotation)
  587. Description:
  588.  
  589.      This  function  returns  the  X  direction  from  the specified R
  590.      direction.
  591.  
  592.  
  593. -----------------------------------------------------------------------------
  594.  
  595. Function: JoyRToJoyY
  596. =========
  597.      Syntax: n.b=JoyRToJoyY(rotation)
  598. Description:
  599.  
  600.      This  function  returns  the  Y  direction  from  the specified R
  601.      direction.
  602.  
  603.  
  604. -----------------------------------------------------------------------------
  605.  
  606. Function: JoyXYToJoyR
  607. =========
  608.      Syntax: n.b=JoyXYToJoyR(x,y)
  609. Description:
  610.  
  611.      This  function returns the R direction from the specified X and Y
  612.      directions.
  613.  
  614.  
  615. =============================================================================